White Paper
from Pocket Soft
90 to 99% compression, in typical usage, saves money distributing
fixes and updates. .RTPatch Professional works at the binary level
with executables, data, text; any type of file. .RTPatch Professional
consists of two steps:
1) Patch Build
2) Patch Apply
.RTPatch Build compares the old and new systems. A system can
be one file or many files scattered throughout directories on
your hard disk. Patch Build analyzes the two systems to decide
what files have been modified, deleted, added, and renamed between
the two systems. It then creates a patch file containing the changes
needed to convert an old system to a new one. This patch file
is automatically compressed to make it even smaller.
The second step is applying the patch file to an old system, such
as one existing on an end-user's machine. You provide your end
user with the patch application step, Patch Apply, and the patch
file.
You can distribute patch files and the Patch Apply program on
a floppy disk, on an electronic bulletin board, via modem, etc.
Extensive error checking is performed both at the time that patch
file is constructed and when it is applied on the end-user's machine,
ensuring the integrity of the updated system.
The patch application program can also create backup copies of
the files affected by the patch so that you can reconstruct the
original system, if needed.
.RTPatch professional is available for the following platforms:
OS/2®
UNIX®
Windows®
Windows NT®
Windows 95
DOS
Building a patch may be as simple as simply passing two directory
names to PATCHBLD on the command line, a directory that contains
your old system and one that contains your new system. For example:
PATCHBLD OLDSYS NEWSYS
If the directory OLDSYS contains subdirectories, simply append
a /s (DOS) or a -s (UNIX) to the directory name; if the directory
NEWSYS contains subdirectories, simply append a /f (DOS) or a
-f (UNIX) to the directory name. Most users can build patches
this simply.
To invoke some of the special features of PATCHBLD, such as handling
serialized files, updating multiple systems with a single patch,
and updating a variety of older versions to the current version
with the same patch, you must use a command file. A command file
also allows greater control over which files in a directory tree
PATCHBLD should compare. A command file is simply an ASCII text
file giving commands to PATCHBLD one per line.
You can control PATCH behavior through command file switches.
For instance, if you want PATCH to continue applying patches after
it fails to find a file which it intends to patch, you can put
the IGNOREMISSING command in the PATCHBLD command file. PATCHBLD
command file commands that affect the behavior of PATCH are also
available as PATCH command line switches.
There are four actions that PATCHBLD may take with each particular
file in a system. A patch file is actually a concatenation of
individual patching actions for each file in a system. The four
possible actions are:
PATCHBLD also outputs an ASCII text file with an .RTD extension,
called the documentation file. This file lists each of the files
affected by the patch, and which of the above four actions applies
to each one.
There are several ways to apply the output of the PATCHBLD program,
henceforth known as a patch file, to the original system of files.
The easiest is to send the end-user the small command line executable
PATCH, along with the patch file. You need only send PATCH the
first time you send an update to an end-user. PATCH takes up to
three optional parameters in any order:
PATCH [switches] [update directory] [patch file name]
The [switches] parameter takes any of the switches that toggle
a PATCH feature. Switches toggle features such as the automatic
backup of the old system prior to the patch application; the ability
of PATCH to back out of changes already made to files in the event
of error; whether or not PATCH searches on the path or in subdirectories
for files to update; and whether PATCH will quit when it fails
to find a file which it intends to update. Each of these attributes
has a default which you may toggle either at build or apply time.
The [update directory] parameter specifies the directory on the
end-user's system that contains the files to update. In the absence
of this parameter, the update directory is the current directory.
The update directory can have any name on the end-user's system,
since PATCH searches for files to update, not specific directory
names. PATCH will search for files to update in the update directory;
in subdirectories of the update directory; or in directories listed
on the PATH environment variable. You can cause PATCH not to search
in either of the latter two places with the use of switches, described
above.
Note that there are actually three systems involved in the building
and applying of a patch: the old and new systems on your machine,
and the end-user's system. The end-user's system need only be
like the old system on your end in that it contains the same files.
The directory structure in which these files reside on the end-user's
system need not be identical to the directory structure on your
machine.
The [patch file name] parameter gives the name of the patch file
to apply. In the absence of this parameter, the default is "PATCH.RTP".
You can name the patch file with the PATCHBLD -O:<name>
command line option, or the PATCHBLD OUTPUT command file command.
Each attribute of PATCH behavior for which there is a switch has
a default setting, and the switch can toggle the setting on or
off in a PATCHBLD command file or on the PATCH command line. Thus,
you can either define certain modes of PATCH behavior when you
build the patch, or have your end-users choose the behavior when
they apply the patch.
There are alternative methods of applying a patch file to shipping
the command line executable PATCH and having your end-users run
it. The memory usage of PATCH is small, and switches (-NOMESSAGE,
-QUIET) are available to suppress all screen output of PATCH;
thus, you can seamlessly spawn patch from your own installation
program. Some supported platforms include the ability to program
a graphical interface to the patch apply process, and also the
ability to send a self-applying patch file.
The backup feature allows the automatic backup of all the old
system files prior to the application of the patch. With this
feature, PATCH copies the update directory, including all subdirectories,
to a backup directory. PATCH writes a batch file that the end-user
can run to restore the original system.
PATCH can back out of any changes made to the end-user's files
on error or interruption of the apply process due to power outage,
ctrl-c, or turning off the computer. By default, if PATCH encounters
an error condition and stops, or if something interrupts PATCH,
the files that PATCH has already updated will remain updated,
and the file that PATCH has currently open will not be updated.
However, if you enable the undo feature, the original system will
be intact.
PATCH checks two things before it will apply a modify patch for a file. When PATCH finds a file of the appropriate name, it first compares the size of the file with the size of the original. If the file size is the same, it then calculates a checksum for the file, and compares it to a checksum calculated for the original file. If the file passes this test, it is definitely the same as the original, and PATCH applies the changes. If the file does not pass, then PATCH continues looking for a file of the same name, until it has exhausted all search possibilities. In this event, PATCH either quits with an error or continues with a warning, based on a parameter set at build or apply time.
You can password protect a patch file to ensure that only end-users
authorized to apply the patch file can do so.
This feature allows the updating of a variety of different older
versions to a single current version with one patch file. For
example, history patching is useful if you do not know which end-users
have which versions of a software system. Furthermore, history
patching works on a file-by-file basis, so that an end-user might
have files mixed from several different versions, and still apply
one patch file to become current. History patching allows you
to create a patch file that will update every end-user to the
current version, regardless of which version or combination of
versions with which they began.
PATCH syntax assumes that all files that require updating lie
under one directory, called the update directory. However, this
assumption may not suffice for certain software installation schemes.
For instance, an installation program might install the main software
files in one directory, and some supporting files in another directory
on another drive. .RTPatch allows you to deal with such a complicated
software installation.
Files may have unique serial numbers or certain regions configurable
by the end-user that might contain a company name or other information.
Such information that differs from file to file would ordinarily
cause PATCH not to apply a patch (since the checksums for files
with different serial numbers or data would not match). PATCHBLD
allows you to deal with serial numbers or other regions in a file
which may differ from user to user. You may have PATCH ignore
or retain from the old to new version certain portions of a file,
specified at build time by address and length. Furthermore, you
may have PATCH insert a new serial number in a file.
You may include a temporary file in a patch file which PATCH uncompresses
upon applying the patch file and deletes after the patching process
completes. You may also run any command line during the patching
process. These features allow for powerful customization of the
patch applying process. PATCH can execute the temporary file using
the execution hook, thus allowing custom file processing in the
background while the updating continues. Furthermore, the execution
hook allows custom patching not covered by the many other features
of PATCH. For example, you could use this feature to create an
empty subdirectory, something which PATCH could not ordinarily
do.
.RTPatch provides utility programs that allow you to locate strings
of ASCII characters or bytes in a file. These programs are useful
in conjunction with the serial number features described above.
.RTPatch also includes a utility that compares files and indicates
whether the files are different and where they differ. .RTPatch
provides utilities for splitting a patch file across diskettes,
and putting thus split patch files back together.
Memory Needed at Build Time
Building Patches for Compressed or Encrypted Files
PATCHBLD will build inefficient patch files for files that have
been compressed with some utility (PKZIP, LHA, etc.). You might
find that the patch file is larger than either of the original
files. Encrypted files also may cause inefficient patch file sizes.
Pocket Soft, Inc. phone: (800)826-8086 PO Box 821049 (713)460-5600 Houston, TX 77282-1049 fax: (713)460-2651 USA URL: http://www.pocketsoft.com Email: info@pocketsoft.com